swagger: '2.0'
info:
  version: 1.0.0
  title: 'Opiskeluoikeus, ilmoittautuminen ja läsnäolo API'
  description: >
    Tämä skeema on tuotettu Ristiinopiskelu-kärkihankkeelle 2017 ja perustuu
    SUOMEN VIRTUAALIYLIOPISTON OPETUSTIETOMÄÄRITYKSIÄ N:O 5 'M0:
    Opiskeluoikeuksien tiedot korkeakouluissa skeeman versioon 1.1,' jota on
    täydennetty KOSKI ja VIRTA-määrityksillä.
  contact:
    name: Pekka Järveläinen
    email: pj@csc.fi
  license:
    name: CC0
    url: 'https://creativecommons.org/licenses/by/4.0/'
consumes:
  - application/json
produces:
  - application/json
basePath: /v1
paths:
  /opiskeluoikeus/:
    post:
      description: 'Opiskelijan, opinto-oikeuksien haltijan henkilöntietojen siirto'
      operationId: ilmoittautuminen
      produces:
        - application/json
      parameters:
        - name: M0-opiskelija
          in: body
          description: M0-opiskelija
          required: true
          schema:
            $ref: '#/definitions/m0'
      responses:
        '200':
          description: kuittaus
          schema:
            $ref: '#/definitions/kuittaus'
        default:
          description: unexpected error
          schema:
            $ref: '#/definitions/errorModel'
definitions:
  m0:
    type: object
    required:
      - lähettäväorganisaatio
      - vastaanottavaorganisaatio
      - lähetysaika
      - oletuskieli
      - opiskelija
    properties:
      lähettäväorganisaatio:
        $ref: '#/definitions/organisaatio'
      vastaanottavaorganisaatio:
        $ref: '#/definitions/organisaatio'
      lähetysaika:
        type: string
        format: date-time
        description: 'M0 0.3 RFC 3339, section 5.6'
      purkuaika:
        type: string
        format: date-time
        description: >
          jira CSCRISTIINOPISKELU-184 viestin purkuhetken aikaleima on mahdoton
          alkuperäiselle lähettäjälle, mutta matkalla...
      oletuskieli:
        type: string
        description: M0 0.4 ISO 639 kaksikirjaiminen
        minLength: 2
        maxLength: 2
      opiskelija:
        $ref: '#/definitions/opiskelija'
      paluuarvo:
        type: number
        format: int32
        enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          - 5
        description: >-
          Ilmoittautumisen status: 0. 'Ei ilmoittautunut sisu:NOT_ENROLLED –
          Opiskelija on lisännyt toteutuksen kalenteriinsa, mutta ei ole vielä
          ilmoittautunut' 1. jonossa, PENDING, PROCESSING  2. hyväksytty,
          ACCEPTED, ENROLLED – Lopullinen laskenta on tehty ja vahvistettu,
          opiskelija pääsi sisään 3. hylätty, CANCELED, REJECTED - Lopullinen
          laskenta on tehty ja vahvistettu, opiskelija ei päässyt sisään 4.
          ABORTED_BY_STUDENT – Toteutuksen ollessa käynnissä, opiskelija on
          keskeyttänyt toteutuksen suorituksen 5. ABORTED_BY_TEACHER –
          Toteutuksen ollessa käynnissä, opettaja on keskeyttänyt opiskelijan
          toteutuksen suorituksen
      lisätietoja ilmoittautumisen tilasta:
        type: string
        description: >
           Ilmoittautumisaikana opiskelijan pitäisi pystyä näkemään kotikorkeakoulunjärjestelmässä esim. kuinka moni on ilmoittautunut toteutukselle suhteessa kiintiöön, että saa käsitystä onko mitään mahdollisuutta mahtua opetukseen mukaan.
           Tässä on tiettyä monimutkaisuutta, koska ilmoittautumisaikana tieto voi olla yksittäisen opiskelijan osalta olla erilainen, riippuen kohdekorkeakoulussa käytettävistä valinnan kriteereistä.
              -          ilmoittautumisjärjestystä käytettäessä voidaan lähes reaaliaikaisesti nähdä monentenako opiskelija on ilmoittautunut
              -          laskennallista kriteeriä käytettäessä (esim. tietyn alan opiskelijat ennen muita tms.), voidaan tehdä järjestys tietyllä hetkellä, mutta se voi muuttua
              -          arvontaa käytettäessä opiskelijan tilanteesta ei ole tietoa ennen hyväksymistä, voidaan esittää vain moniko on ilmoittautunut ja mikä kiintiö on
           'Samin sähköposti Mon, 19 Feb 2018 11:35:06 +0000 (2018-02-19 13:35:06)'
    description: 'M0'
  opiskelija:
    type: object
    description: >-
      Jos kansalaisuus suomi, on hetu pakollinen. Jos kansalaisuus muu, on oid
      pakollinen. Purkavan järjestelmän on tarkistettava!
    properties:
      oid:
        type: string
        description: oppijanumero Oid
      henkilötunnus:
        type: string
        description: M0 1.1
      generoituhenkilötunnus:
        type: string
        description: M0 1.2 Ei saa käyttää viralliselle
      vastaanottotunnus:
        type: string
        description: M0 1.3 Jos tiedetään tunnus vastaanottavassa organisaatiossa
      lähdetunnus:
        type: string
        description: M0 1.4 oma opiskelijanumero tai tunnus
      eppn:
        type: string
        description: 'EduPerson Principal Name (Jaakon sähköposti 5 Feb 2018 09:16:40)' 
      etunimi:
        type: string
        description: M0 1.5
      sukunimi:
        type: string
        description: M0 1.6
      syntymäaika:
        type: string
        description: M0 1.7
      sukupuoli:
        type: number
        format: int32
        description: M0 1.8 Mutta arvot virran mukaan 1. mies 2. nainen 9 tunetematon
      osoitteet:
        type: array
        items:
          $ref: '#/definitions/osoite'
        description: M0 1.9 VRK+opiskelupaikkakunnan osoite
      maa:
        type: string
        description: M0 1.10 Opintopolun koodistopalvelusta
      kotikunta:
        type: string
        description: M0 1.11 Opintopolun koodistopalvelusta
      kansalaisuus:
        type: string
        description: M0 1.12 Opintopolun koodistopalvelusta
      äidinkieli:
        type: string
        description: 'M0 1.13 Tilastokeskus???, tuntematon 999'
      asiointikieli:
        type: string
        description: Uusi
      sähköposti:
        type: array
        items:
          type: string
        description: 'M0 1.14, mahdolistettiin useampia'
      verkkosivu:
        type: string
        description: M2 3.1.6 URL
      puhelin:
        type: string
        description: kansainvälinen muoto +358
      opiskeluoikeus:
        $ref: '#/definitions/opiskeluoikeus'
  opiskeluoikeus:
    type: object
    description: M0 1.15
    required:
      - tunnisteet
      - vastuuorganisaatio
    properties:
      tunnisteet:
        $ref: '#/definitions/tunnisteet'
      tiedot:
        $ref: '#/definitions/tiedot'
      tila:
        $ref: '#/definitions/tila'
      nimi:
        type: string
        description: M0 1.15.4
      vastuuorganisaatio:
        $ref: '#/definitions/organisaatio'
      tyyppi:
        type: number
        format: int32
        description: >-
          https://confluence.csc.fi/display/VIRTA/Tietovarannon+koodistot#Tietovarannonkoodistot-Opiskeluoikeudentyyppi,Studierättenstyp
      kattavuus:
        type: string
        description: >
          'M0 1.15.6 tai esim. maisteri tai Funetin EduPerson Student Category
          TUTKINNON OPISKELUOIKEUDEN KATTAVUUS (YLIOPISTOT, lähde: M0): 1=Alempi
          korkeakoulututkinto 2=Ylempi korkeakoulututkinto 3=Lisensiaatin
          tutkinto 4=Tohtorin tutkinto 5=Ammatillinen jatkotutkinto 9=Avoin
          yo-opiskelu OPISKELUOIKEUDEN KATTAVUUS (AMK, lähde: AMKOTA,
          Tilastokeskus): 1=Amk-tutkintoon johtava nuorten koulutus (AMKOTA,
          Tilastokeskus) 2=Amk-tutkintoon johtava aikuiskoulutus (AMKOTA,
          Tilastokeskus) 3=Erikoistumisopinnot (AMKOTA, Tilastokeskus) 4=Avoin
          amk-koulutus (AMKOTA) 5=Ammatillinen opettajankoulutus (AMKOTA,
          Tilastokeskus) 6=Ylempi ammattikorkeakoulututkinto (AMKOTA,
          Tilastokeskus) MUUT OPISKELUOIKEUDET (YLIOPISTOT, lähde:
          Tilastokeskus): 670=Erilliset erityisopettajan opinnot 674=Erilliset
          erityislastentarhanopettajan opinnot 678=Erilliset opinto-ohjaajan
          opinnot 901=Erilliset arvosanat ja opintokokonaisuudet, kuulustelut ja
          kurssit 904=Erilliset aineenopettajan kasvatustieteelliset opinnot
          910=Erilliset opinnot, jotka aiotaan sisällyttää toisessa kotimaisessa
          yliopistossa tai muussa oppilaitoksessa suoritettavaan tutkintoon
          912=Ammatillisten oppilaitosten ja kansan- ja kansalaisopistojen
          opettajille tarkoitetut erilliset kasvatustieteelliset opinnot
          915=Erilliset opinnot ulkomaalaisena vaihto-opiskelijana (yhteistyö
          ulkomaalaisen korkeakoulun kanssa) tai muut ulkomaalaisten
          opiskelijoiden määräaikaiseen opiske- lu-oikeuteen pohjautuvat opinnot
          918=Ulkomaisen tutkinnon pohjalta tapahtuva pätevöitymiskoulutus
          919=Kansainväliset koulutukset ja opinto-ohjelmat 922=Kelpoisuus- ja
          pätevöitymiskoulutus tai muu täydennyskoulutus erilaisen pohja-
          koulutuksen omaaville henkilöille 999=Muu tai tuntematon tutkintoon
          johtamaton koulutus'
      koulutusluokitus:
        type: integer
        format: int32
        maximum: 1000000
        description: 'ISCED 2011 6-numeroinen EU:n laajuinen (uusi! ei M0)'
      ilmoittautumisKysymyksenVastaus:
        type: string
        description: 'Opetusryhmän valinta, kysymyksen tai vaihtoehtojen vastaus'
      materiaaliValintaVastaus:
        type: string
        description: 'Valittu opetusmateriaali, mistä kirjoittaa esseen (uusi!)'
      verkostoTunniste:
        type: array
        description: >-
          Oid. M0 1.15.8tai9 (uusi!) Verkostomäärittelyt, mihin opiskelija
          kuuluu
        items:
          type: string
      verkostoKuvaus:
        type: array
        description: >-
          Verkostojen selväkielinen nimet tai kuvaukset (edelliseen koodit
          vastaavasti)
        items:
          type: string
  tunnisteet:
    type: object
    description: M0 1.15.1
    required:
      - organisaatio
      - opiskeluoikeus
    properties:
      organisaatio:
        $ref: '#/definitions/organisaatio'
      opiskeluoikeus:
        type: string
        description: M0 1.15.1.2 pihvi
  tiedot:
    type: object
    description: M0 1.15.2
    required:
      - muoto
    properties:
      muoto:
        type: string
        description: M0 Taulukko 2 1.1 MIME-tyyppi (RFC2048)
      linkki:
        type: string
        description: M0 Taulukko 2 1.2 URL
      tiedot:
        type: string
        description: M0 Taulukko 2 1.3 Vaihtoehtoinen URLlin kanssa. 1.1 mukaista
  tila:
    type: object
    description: M0 1.15.3
    required:
      - nimi
      - alkuaika
      - loppuaika
    properties:
      nimi:
        type: string
        description: >-
          M0 1.15.3.1
          https://confluence.csc.fi/display/VIRTA/Tietovarannon+koodistot#Tietovarannonkoodistot-Opiskeluoikeudentila,Studierättersstatus
        enum:
          - 1 aktiivinen
          - 2 optio
          - 3 päättynyt
          - 4 passivoitu
          - 5 luopunut
      tarkenne:
        type: string
        description: M0 1.15.3.2
        enum:
          - Ei ilmoittautunut
          - Ensisijainen
          - Päätoiminen
          - Sivutoiminen
          - Verkkopalveluiden käyttöoikeus
          - Kirjaston käyttöoikeus
      alkuaika:
        type: string
        format: date
        description: 'M0 1.15.3.3 M0ssa ei pakollinen, mutta tässä kyllä'
      loppuaika:
        type: string
        format: date
        description: 'M0 1.15.3.4 M0ssa pakollinen, mutta tässä arvio!'
  organisaatio:
    type: object
    required:
      - tunniste
      - organisaation nimi
    properties:
      tunniste:
        type: string
        description: oid
      organisaation nimi:
        type: string
        description: M2 4.1.2
      yksikön nimi:
        type: string
        description: M2 4.1.3 "Lääketieteellinen tiedekunta"
      nimiselite:
        type: string
        description: M2 4.1.4 "Patologian laitos"
      postiosoite:
        $ref: '#/definitions/osoite'
      käyntiosoite:
        $ref: '#/definitions/osoite'
      puhelin:
        $ref: '#/definitions/puhelin'
  osoite:
    type: object
    properties:
      katu:
        type: string
        description: M2 4.1.5/6.1
      postinumero:
        type: number
        format: int32
        description: M2 4.1.5/6.2
        maximum: 100000
      postitoimipaikka:
        type: string
        description: M2 4.1.5/6.3
      maa:
        type: string
        description: M2 4.1.5/6.4
  puhelin:
    type: object
    required:
      - numero
    properties:
      numero:
        type: string
        description: M2 4.1.7.1 +358 kansainvälinen muoto
      selite:
        type: string
        description: M2 4.1.7.2 "esim. kanslia"
  yhteistyoverkosto:
    type: object
    required:
      - tunnus
      - nimi
    properties:
      tunnus:
        type: string
        description: URI M2 1.1.5.1
      nimi:
        type: string
        description: M2 1.1.5.2
  kuittaus:
    type: object
    required:
      - code
    properties:
      code:
        type: integer
        format: int32
  errorModel:
    type: object
    required:
      - code
      - message
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
